home *** CD-ROM | disk | FTP | other *** search
/ Commodore Free 11 / Commodore_Free_Issue_11_2007_Commodore_Computer_Club.d64 / t.swl v1 < prev    next >
Text File  |  2023-02-26  |  10KB  |  354 lines
  1. u           SWL version 1.00
  2.  
  3.  http://www.lyonlabs.org/commodore/
  4.   c64.html
  5.  
  6. Information & help file This file
  7. describes the SWL library for the Power
  8. C compiler (Commodore 64). If you don't
  9. have a copy of the compiler, get it on
  10. my website, http://www.lyonlabs.org
  11.   (see the C= 64 section).
  12.  
  13. Please send bug reports or
  14. documentation errors to me (Glenn
  15. Holmer) The SWL library is a set of
  16. text-based C functions written in
  17. assembler using C-ASSM (also available
  18. on my web site). SWL provides:
  19.  
  20. -string input with restricted
  21. character and input length
  22.  
  23. -bordered windows that restore the
  24. screen beneath them when they are
  25. closed
  26.  
  27. -menus with submenus
  28.  
  29. -simple widgets (label, text, checkbox,
  30. listbox) that can be grouped It is
  31. distributed as a .D64 image containing
  32. source, object files, a library file,
  33. this documentation, & demo programs.
  34. The basics of using SWL in your
  35. programs are covered here; for detailed
  36. API documentation, see source files:
  37.  
  38.  swl-menu.a swl-menuutil.a swl-wdg.a
  39.  swl-wdgutil.a swl-asm.a swl-irq.a
  40.  
  41. You can see which functions are in each
  42. source file by looking at the .def
  43. statements at the beginning of each
  44. file.To use SWL in your C programs,
  45. include the header swl.h & link with
  46. the library swl.l. The library file &
  47. the 6 object files corresponding to the
  48. source files above must be on your work
  49. disk.
  50.  
  51. Notes on the SWL API Although SWL was
  52. meant to be called from C, some APIs
  53. have assembler entry points because
  54. they call each other. See the source
  55. code for these entry points & their
  56. calling conventions.
  57.  
  58. TEXT INPUT The basic building block of
  59. SWL is text input routine, wchrin():
  60.  
  61. wchrin(string, mask) char *string;
  62. int mask;
  63.  
  64. Before calling wchrin(), call
  65. swlDinit() to enable the IRQ routine
  66. for the keyboard; you can disable it
  67. again later by calling swlDkill(). The
  68. IRQ service routine has two exported
  69. hooks: ihooktop and ihookbot (see
  70. swl-irq.a).wchrin()'s input can be
  71. restricted by ORing together the
  72. following values in the exported
  73. variable "mask":
  74.  
  75. $01 (MSKDNUM): numeric input only $02
  76. (MSKDALW): allow only specified
  77. characters $04 (MSKDEND): use input
  78. terminator table ("endkeys") $80
  79. (MSKDCHK): checkbox input: 1 character
  80. only,
  81.  
  82.  space only, toggles a checkmark
  83.  
  84. MSKDNUM and MSKDALW can be combined
  85. (e.g. numeric with decimal point), but
  86. MSKDCHK trumps both (it is meant for
  87. the checkbox widget described below).
  88. The allowed keys and end keys are in
  89. 16-byte character arrays named
  90. "allowed" and "endkeys". To add or
  91. remove end keys for an individual
  92. call to wchrin, call addEnder &
  93. rmvEnder (in swl-irq.a). For allowed
  94. keys, just strcpy the characters to the
  95. allowed array (there is an API for this
  96. if you are using widgets).
  97.  
  98. WINDOWS SWL supports text-based
  99. windows, which are written directly to
  100. screen memory. The area of the screen
  101. occupied by the window is buffered &
  102. restored when the window is closed. Up
  103. to 8 windows at a time can be open, &
  104. they can overlap.
  105.  
  106. openWnd(left, top, width, height,
  107. title) int left, top, width, height;
  108.  
  109. clsWnd( )
  110.  
  111. There is also a routine to draw a box
  112. on the screen, which is not buffered:
  113.  
  114. drawBox(left, top, width, height) int
  115. left, top, width, height;
  116.  
  117. CURSOR LOCATION There are 2 routines to
  118. set the cursor location:
  119.  
  120. locate(x, y) int x, y;
  121.  
  122. wlocate(x, y) int x, y;
  123.  
  124. locate() sets the x and y cursor
  125. position (counting from 0) & clears the
  126. screen line link table. wlocate()
  127. checks to see if a window is open: if
  128. so, it locates the cursor within the
  129. window, otherwise it calls locate().
  130. wlocate() returns FALSE
  131.  
  132. (0) if the coordinates are out of range
  133. for the window. MENUS SWL has support
  134. for menus, which can appear anywhere on
  135. the screen. Menus are represented by a
  136. menu structure with a pointer to a
  137. singly-linked list of menu item
  138. structures. A submenu is a menu item
  139. with a pointer to the submenu. There
  140. are "constructor" functions for menus &
  141. menu items, as well as functions to add
  142. items & submenus to a menu:
  143.  
  144. struct *menu newMenu(left, top, parent,
  145. title) int left, top; struct menu
  146. *parent; char *title;
  147.  
  148. struct *menuitem newItem(text) char
  149. *text;
  150.  
  151. addItem(menu, item) struct menu *menu;
  152. struct item *item;
  153.  
  154. struct *menuitem addmenu(menu
  155.  
  156. submenu) struct menu *menu, *submenu;
  157. See the header file for the structure
  158. definition (note that there are fields
  159. called mExtend & iExtend that can be
  160. used to "subclass" these structures).
  161. There are 2 types of menu:
  162.  
  163. struct *menu doMenu(menuptr) struct
  164. menu *menuptr;
  165.  
  166. struct *menu doList(menuptr) struct
  167. menu *menuptr;
  168.  
  169. doMenu() draws the menu within a
  170. window and restores the screen after-
  171. ward; doList() draws the menu using
  172. drawBox() and does not restore the
  173. screen. In addition, doList() ignores
  174. submenus. It is meant for simple
  175. listboxes (see the listbox widget
  176. described below). Menus are exited with
  177. Enter (ENTER) or F5 (KEYDEXIT), & end
  178. keys are respected, meaning you can
  179. check the value of endkey to see how a
  180. menu was exited (you can also check the
  181. menu's mEndkey field). The return value
  182. is the menu structure the user exited
  183. from (which may be a submenu), or 0 if
  184. a top-level menu was dismissed with F5.
  185.  
  186. If a menu item was chosen with Enter,
  187. the menu structure's mChosen field will
  188. be set to TRUE
  189.  
  190. (1) and the mCuritem field will
  191. indicate which item was selected (you
  192. will have to walk the item structures
  193. with a counter to get to it; see
  194. menutest.c for an example). Menu items
  195. can contain a pointer to a dispatch
  196. function (iAction), so you can just
  197. check to see if that's non-null & call
  198. it if so. WIDGETS
  199.  
  200. The widget APIs pull together all the
  201. elements of SWL to allow the creation
  202. of input screens or dialogs where the
  203. user can use the keyboard to move back
  204. & forth among several fields & accept
  205. or cancel the input as a whole. The
  206. keys, inspired by Q-Link, are F7/F8 to
  207. move forward & backward among the
  208. widgets, F1 to accept, & F5 to cancel.
  209. They are defined in swl.h.
  210.  
  211. A group of widgets is a circular,
  212. doubly-linked list of widget
  213. structures. There are four types of
  214. widgets: labels, text input, checkbox,
  215. & listbox (all of which share the same
  216. structure). All widgets are displayed
  217. when doWidget() is first called. During
  218. the data entry loop, label widgets are
  219. ignored, but text inputs are handled by
  220. wchrin(). Checkbox widgets are also
  221. handled by wchrin(), but with the
  222. special flag
  223.  
  224. MSKDCHK, which allows only a single
  225. space as input and uses it to toggle
  226. between a check mark & an underscore.
  227. Listbox widgets call the doList() form
  228. of menu. As with menus, there are
  229. "constructor" functions as well as a
  230. function to add them to a group:
  231.  
  232. struct *widget newLbl(left, top,
  233. text) int left, top; char *text;
  234.  
  235. struct *widget newTxt(left, top,
  236. text) int left, top; char *text;
  237.  
  238. struct *widget newChk(left, top,
  239. state, dummy) int left, top, state;
  240. char *dummy;
  241.  
  242. struct *widget newList(left, top,
  243. menu) int left, top; struct menu
  244. *menu;
  245.  
  246. addWdg(widget, firstWdg) struct
  247. widget *widget, *firstWdg) ;
  248.  
  249. Each widget has its own set of end keys
  250. & allowed keys. End keys are added to
  251. the endkeys table when each widget
  252. gains focus, & removed afterward (since
  253. the function keys must remain active),
  254. but each widget's allowed keys replace
  255. the allowed keys table while it has
  256. focus. As with menus, the widget
  257. structure has a field named wExtend for
  258. "subclassing" (in fact, the listbox
  259. widget uses it to store the menu
  260. pointer). To display a group of
  261. widgets, call initWdg() to set up the
  262. function keys (make sure to call
  263. swlDinit() as well if you are using
  264. text or checkbox widgets) , then call
  265. doWidget() with a pointer to the first
  266. widget of the group:
  267.  
  268. doWidget(first, inWindow) struct
  269. widget *first; int inWindow;
  270.  
  271. The inWindow argument indicates whether
  272. the widgets are contained within a
  273. window; if so, the window cursor
  274. location routine is used, & any widgets
  275. that would extend beyond the right edge
  276. of the window are truncated before
  277. display. When doWidget() returns, call
  278. killWdg( ) to remove the function keys
  279. from the endkeys table, & swlDkill() if
  280. you were using text or checkbox
  281. widgets.
  282.  
  283. The return value is a pointer to the
  284. widget the user exited from (or 0 if
  285. any screen locations are invalid) As
  286. with menus, widgets can have dispatch
  287. functions. With widgets, however, the
  288. loop will exit as soon as a widget with
  289. a dispatch routine loses focus. The
  290. reason for this is so that one widget
  291. can affect another (e.g. a checkbox
  292. changing another widget from text input
  293. to a label to disable it)
  294.  
  295. To make this happen, SWL would have to
  296. call the C dispatch function from
  297. within the widget loop's assembler
  298. code, which I was not prepared to do
  299. (it would also have required an add-
  300. itional flag to indicate that the
  301. dispatch should be called immediately).
  302. The solution is to check manually for a
  303. dispatch function when the loop exits,
  304. & handle this on a case-by-case basis
  305. (re-entering the loop after the
  306. dispatch has been called if you want to
  307. continue)
  308.  
  309. There is an example of this technique
  310. in the demo program wdgtest.c.
  311.  
  312. UTILITY ROUTINES SWL also provides some
  313. utility routines:
  314.  
  315. int banner(text, edge, align) char
  316. *text; int edge, align;
  317.  
  318. Draws a banner at the top or bottom
  319. edge of the screen in reverse video,
  320. aligned left, center, or right. See
  321. swl.h for constants (BNRD for edge &
  322. ALND for alignment)
  323.  
  324. char wgetchar() ;
  325.  
  326. Reads a character from the keyboard
  327. (blocks until a key is pressed)
  328.  
  329. char wgetkey() ;
  330.  
  331. Reads a character from the keyboard
  332. (non-blocking, may return 0)
  333.  
  334. ASSEMBLER UTILITY ROUTINES If you are
  335. using assembler, there are some add-
  336. itional routines available that are not
  337. callable from C. These are documented
  338. in swlasm.a & swl-irq.a: multiply
  339. (integer multiply) beep (sound a bell)
  340. savtemp (save temporary variable area)
  341. rsttemp (restore temporary variable
  342.  area)
  343. charout (write a character to screen)
  344. scnout (write a screen code to screen)
  345.  
  346. KNOWN BUGS There are no known bugs at
  347. this time. Please send bug reports to
  348. the address at the top of this file.
  349.  
  350. KNOWN LIMITATIONS There is no support
  351. for screen colors or custom character
  352. sets. The APIs for adding end keys &
  353. allowed keys are not consistent
  354.